Summary of the Pull Request

Add build-system integration to the Microsoft.WSL.Containers NuGet package so developers can declaratively build WSLC container images and export them to tar files as part of their MSBuild (C++/C#) and CMake workflows, with full incremental rebuild support.

Developers declare <WslcImage> items (MSBuild) or call wslc_add_image() (CMake) in their project, and the build system automatically runs wslc image build followed by wslc image save after the main build, skipping both when sources haven't changed.

PR Checklist

• Closes: Link to issue #xxx
• Communication: I've discussed this with core contributors already. If work hasn't been agreed, this work might be rejected
• Tests: Added/updated if needed and all pass
• Localization: All end user facing strings can be localized
• Dev docs: Added/updated if needed
• Documentation updated: If checked, please file a pull request on our docs repo and link it here: #xxx

Detailed Description of the Pull Request / Additional comments

New files

Usage — MSBuild (C++ / C#)

<ItemGroup>
  <WslcImage Include="echo-server"
             Image="echo-server:latest"
             Dockerfile="container\server\Dockerfile"
             Context="container\server"
             Sources="container\server;container\shared"
             TarLocation="$(OutDir)echo-server.tar" />
</ItemGroup>

• Image is the full image reference (may include a tag); :latest is appended automatically when no tag is given.
• TarLocation is the output path for the saved tar (defaults to $(OutDir)<Identity>.tar).
• Set <WslcPruneAfterBuild>true</WslcPruneAfterBuild> to also run wslc image prune after save (off by default).

Usage — CMake

find_package(Microsoft.WSL.Containers REQUIRED)
wslc_add_image(echo-server
    IMAGE        ghcr.io/myorg/echo-server:latest
    DOCKERFILE   container/Dockerfile
    CONTEXT      container/
    SOURCES      container/src/*.cpp container/src/*.h
    TAR_LOCATION ${CMAKE_CURRENT_BINARY_DIR}/echo-server.tar
)
add_dependencies(my_app echo-server)

• IMAGE is the container image reference (required); :latest is appended automatically when no tag is given.
• TAR_LOCATION defaults to ${CMAKE_CURRENT_BINARY_DIR}/<target>.tar. The tar is removed by cmake --build . --target clean (and Visual Studio's Clean).
• Pass PRUNE_AFTER_BUILD to also run wslc image prune after save (off by default).

Key design decisions

• Image build + save chain — wslc image build produces the image; wslc image save -o <path> then exports it to a tar that downstream code can load via WslcLoadSessionImageFromFile or wslc image load. Both steps run as part of the build, with full incremental tracking.
• Atomic save via .tmp + rename — wslc image save uses CREATE_ALWAYS, which truncates the destination on entry. The integration writes to <tar>.tmp and renames on success (cmake -E rename / MSBuild <Move>), so a failed save never leaves a partial tar that would mislead the incremental check.
• Incremental tracking — MSBuild Inputs/Outputs and CMake add_custom_command(OUTPUT ...) track sources to skip both image build and save when nothing has changed. MSBuild uses a stamp file for the image build step (since image build doesn't produce a host file); CMake uses the tar directly as the output.
• Optional prune — wslc image prune affects the entire daemon image store, so it's off by default. Opt in via <WslcPruneAfterBuild>true</WslcPruneAfterBuild> (MSBuild) or PRUNE_AFTER_BUILD flag (CMake).
• Semicolon-safe property passing — Sources metadata is escaped via $([MSBuild]::Escape()) before being passed through MSBuild task Properties=, and unescaped at the consumption site, so multi-directory paths work correctly.
• Design-time build guard — All build and validation targets are skipped when $(DesignTimeBuild) == 'true' to avoid slowing the VS IDE.
• wslc CLI on PATH — The integration relies on wslc.exe being on PATH (the WSL MSI puts it there) rather than guessing install locations. CMake uses find_program(WSLC_CLI_PATH wslc); MSBuild defaults WslcCliPath to bare wslc so cmd.exe resolves it.
• Input validation — Dockerfile and Context are required; Identity is validated against invalid filename characters with actionable error codes (WSLC0001–WSLC0004).

Validation Steps Performed

All tests run locally against wslc 2.7.3+ on Windows 11 (26200):